Usenet 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / x / volume6 / xpwdoc / part02 < prev next >

Wrap

Internet Message Format | 1990-04-11 | 66.4 KB

Path: uunet!cs.utexas.edu!usc!zaphod.mps.ohio-state.edu!uakari.primate.wisc.edu!ames!sun-barr!newstop!sun!NSFnet-Relay.AC.UK From: jonm%syma.sussex.ac.uk@NSFnet-Relay.AC.UK (Jonathan Meyer) Newsgroups: comp.sources.x Subject: v06i066: Xpw Documentation, Part02/02 Message-ID: <134354@sun.Eng.Sun.COM> Date: 12 Apr 90 07:36:55 GMT Sender: news@sun.Eng.Sun.COM Lines: 1686 Approved: argv@sun.com Submitted-by: Jonathan Meyer <jonm%syma.sussex.ac.uk@NSFnet-Relay.AC.UK> Posting-number: Volume 6, Issue 66 Archive-name: xpwdoc/part02 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 2 (of 2)." # Contents: doc/ref/PopScrollText doc/ref/PopText # doc/ref/XpwCallMethod doc/ref/XpwMethods doc/ref/XpwResources # doc/man/poplog.man doc/sysdoc/PopWidgets.imp # Wrapped by jonm@csunb on Wed Apr 4 16:16:15 1990 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'doc/ref/PopScrollText' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopScrollText'\" else echo shar: Extracting \"'doc/ref/PopScrollText'\" $19823 characters$ sed "s/^X//" >'doc/ref/PopScrollText' <<'END_OF_FILE' XREF *PopScrollText Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the PopScrollText widget class, which is part of the XPoplog Widget Set. For details of other widgets in the Poplog Widget XSet, see HELP *PopWidgets. For information about the Pop-11 interface to Xthe PopScrollText widget, see HELP *PopScrollText. X X X CONTENTS - (Use <ENTER> g to access required sections) X X -- PopScrollText Widget X -- PopScrollText Resources X -- Information about new resources X -- Handling Exposure Events X -- Actions X -- PopScrollText Translations X -- Methods X -- Scroll Operations X -- Clear Operations X -- Write Operations X -- Cursor and Misc Operations X X-- PopScrollText Widget ----------------------------------------------- X XSuperclass: PopCore X XThe PopScrollText widget is a low level text widget. It provides the programmer Xwith the ability to write text on a window, and scroll it about. The widget also Xnotifies the application of exposure and input events, so that the program can Xredraw the text, process input etc. The PopScrollText widget maintains an XXtNexposedLines resource, which contains a list of lines that need redrawing Xafter an exposure event. It also converts mouse locations into text rows/ Xcolumns, and allows applications to manipulate a text cursor. X XThe widget does not keep a copy of the text that is on the window, and so Xit cannot refresh itself. However, it is very helpful for editors (VED) Xthat already do the hard work of keeping a terminal updated, but don't Xwork with Xlib. X XThere are a variety of operations that can be performed on ScrollText Xwidgets. Most of the operations involve scrolling text, or writing text. X X X-- PopScrollText Resources -------------------------------------------- X XPopScrollText inherits all of the resources of PopCore. The following Xresources are retrieved from the resource database or the argument list Xwhen PopScrollText widgets are created: X X X======================================================================== XName Class RepType Default* Description X======================================================================== XXtNwidth Width Dimension 0 Window width XXtNheight Height Dimension 0 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNforeground Foreground Pixel XtDefault Window foreground color XXtNfont Font FontStruct XtDefault Font for text operations XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont) XXtNtranslations Translations String see below Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for expose events XXtNautoFlush Boolean Boolean TRUE XFlush after methods? XXtNusersGC GC Pointer NULL Graphics Context for ops XXtNmodifiers Parameter Int None event->state modifiers XXtNtopMargin TopMargin Dimension 0 Distance to start of text XXtNleftMargin LeftMargin Dimension 2 Distance to start of text XXtNfontWidth Width Dimension None Width of current font XXtNfontHeight Height Dimension None Height of current font XXtNcursorRow Position Position 0 Cursors Y location XXtNcursorColum Position Position 0 Cursors X location XXtNcursorStatus CursorStatus Boolean TRUE Cursor on/off XXtNmouseX MouseLocation Int None Mouse column XXtNmouseY MouseLocation Int None Mouse row XXtNnumRows Dimension Dimension 24 Text columns XXtNnumColumns Dimension Dimension 80 Text rows XXtNexposedLines Parameter (int *) NULL Lines that need redrawing XXtNkey Key String NULL Ascii string of KeyPress XXtNkeyboardEvent Callback Callback NULL keyboard inputs callback XXtNbuttonEvent Callback Callback NULL Mouse buttonpress events XXtNmotionEvent Callback Callback NULL Mouse motion events XXtNdestroyCallback Callback NULL XtDestroyWidget callback X X X-- Information about new resources ----------------------------------- X XXtNfontWidth XtNfontHeight X fontWidth and fontHeight are the dimensions of the current font in pixels. X The font is expected to have a fixed width. X XXtNtopMargin XtNleftMargin X distance from top and left of window where text starts. X XXtNnumRows, XtNnumColumns X These are based upon the current font and window size. They are calculated X from fontWidth and fontHeight, as well as the width and height of the X window. They are the number of text rows and columns that can be fitted X into the window. Row 0, Column 0 is the top left character of the window. X X Changing the widgets font will cause fontWidth, fontHeight, numRows X and numColumns to be recalculated. Resizing the widget will cause X numRows and numColumns to be recalculated, and exposedLines to be X recreated. X XXtNexposedLines X The 'exposedLines' resource is an array of unsigned ints, with the number X of elements of the array kept the same as the number of rows of text in the X widget. After an exposure event, this array is set as follows: X For each line of text in the window that needs to be redrawn: X the lower short of the array element for that line is set to X the start column and the higher short is set to the end column of text X that needs to be redrawn. See below for more information on exposed lines. X X XXtNcursorRow, XtNcursorColumn X An inverse rectangle is used to represent the cursor. Changing these X resources will cause the cursor to be unplotted and moved to the new X location. Any of the methods that can be applied to the PopScrollText X widget are aware of the cursor, and will replot it if necessary. X XXtNcursorStatus X If this resource is false, or off, the text cursor is not displayed in the X widget. By default the cursor is displayed. X XXtNkeyboardEvent XtNbuttonEvent XtNmotionEvent X These three callbacks are used to notify the client of key, button and X motion events. See below. X XXtNkey X This is the string returned from XLookupKeysym when given the Keysym X of a keyboard event. This resource is set each time a key is pressed X or released. In many cases it will be the ASCII string of the key X that was pressed. X XNOTE: Currently, if you change a PopScrollText's font or margins it DOES XNOT clear the window and force a redisplay. This allows you to display Xmultiple fonts in the same window, though you have to be careful about Xdoing so. If you do want only one font, then call XpwMClearWindow after Xeach font/margin change. X X X-- Handling Exposure Events ------------------------------------------- X XExposure events happen when an area of the window that was occluded is Xmade visible by a raise/lower or map/unmap event. They also occur when a Xscroll operation is used on a region that is partially occluded. (This Xtype of exposure is called GraphicsExsposure). X XWhen repainting text in a PopScrollText widget, the following may be useful: X XThe simplist refresh algorithm would work as follows: X X for each line on display X if exposed_lines(line) is not 0 then X refresh line X endif X endfor X XMore complex redraw algorithms could work out which part of the line Xneeds to be redrawn. The C macros: X X int XpwExposeStart(line_entry) X int XpwExposeEnd(line_entry) X XReturn the start and end column derived from an entry in the exposedLines Xresource. These can be used to calculate exactly which lines need to be Xredrawn. X X-- Actions --------------------------------------------------------------- X X XThe following actions call their associated callback list with data extracted Xfrom the event. X X Name Event Call Data X ------------------- ------------------ ---------------------- X notify-button-event Button Events Button number* X notify-key-event Key Events Keysym of key* X notify-motion-event <Btn>Motion events event->state@ X X*Button number and Keysyms are signed integers. They are positive when X the button/key goes down and negative when the button/key comes up. X X@only calls the callback if mouseX and mouseY resources have changed, ie. X when the mouse moves into a new character cell. X XThe following additional actions are used by the PopScrollText widget: X X Name Event Notes X ---- ------------------ --------------------- X notify-graphics-expose Graphics Expose calls popCallback X highlight-cursor Enter Window X unhighlight-cursor Leave Window X X X-- PopScrollText Translations -------------------------------------------- X XThe default translations for PopScrollText widgets are as follows: X X X "<BtnDown>: notify-button-event() \n\ X <BtnUp>: notify-button-event() \n\ X <Keypress>: notify-key-event() \n\ X <KeyRelease>: notify-key-event() \n\ X <EnterWindow>: highlight-cursor() \n\ X <LeaveWindow>: unhighlight-cursor() \n\ X <GraphicsExpose>: notify-graphics-expose() \n\ X <Motion>: notify-motion-event()"; X X-- Methods -------------------------------------------------------------- X XThe PopScrollText widget responds to all of the PopCore methods. Additionally Xit responds to a set of methods that are used to manipulate the text on the Xwidget. The methods can be grouped as follows: X X Scrolling methods X Clearing methods X Writing methods X Cursor/Misc methods X XIn the case of Scrolling, Clearing and Writing, there is one primative Xgeneric method for each action, and several convenience methods that call Xthe generic method with calculated arguments. There are also several Xmethods that apply the generic Scrolling/Clearing/Writing method at the Xcurrent cursor location. X XMethod Name Arguments Notes X======================================================================== XXpwMScroll col,row,cols,rows,x_dist,y_dist XXpwMScrollScreenUp - XXpwMScrollScreenDown - XXpwMScrollScreenLeft - XXpwMScrollScreenRight - XXpwMScrollLines row, rows, dist XXpwMScrollTail col, row, dist XXpwMScrollTails col, row, rows, dist XXpwMScrollTailLeft col, row XXpwMScrollTailRight col, row XXpwMInsertLineAtCursor - XXpwMInsertCharAtCursor - XXpwMDeleteLineAtCursor - XXpwMDeleteCharAtCursor - XXpwMClear col, row, cols, rows XXpwMClearWindow - XXpwMClearLine row XXpwMClearLines row, rows XXpwMClearTail col, row XXpwMClearTails col, row, rows XXpwMClearChar col, row XXpwMClearLineAtCursor - XXpwMClearTailAtCursor - XXpwMClearCharAtCursor - XXpwMInsert col, row, str, len XXpwMInsertAtCursor str, len XXpwMWrite col, row, index, lines, strs, off,len,clr XXpwMWriteLine col, row, str, len, clr XXpwMWriteLines col, row, index, lines, strs, len, clr XXpwMWriteSubstr col, row, str, off, len, clr XXpwMWriteAtCursor str, len XXpwMCursorTo col,row XXpwMCursorUp - XXpwMCursorDown - XXpwMCursorLeft - XXpwMCursorRight - XXpwMBell volume X X X-- Scroll Operations -------------------------------------------------- X XXpwMScroll X XpwCallMethod(widget,XpwMScroll, col,row,cols,rows,x_dist,y_dist); X Widget widget; X int col, row, cols, rows, x_dist, y_dist; X X Scrolls the region starting at col, row, of width cols and height rows, X by distance x_dist, y_dist. x_dist and y_dist can be positive or negative X integers, and are measured in character cells. If cols or rows are zero, X the current width/height of the window are used. X XXpwMScrollScreenUp XXpwMScrollScreenDown XXpwMScrollScreenLeft XXpwMScrollScreenRight X XpwCallMethod(widget,XpwMScrollScreenUp); X XpwCallMethod(widget,XpwMScrollScreenDown); X XpwCallMethod(widget,XpwMScrollScreenLeft); X XpwCallMethod(widget,XpwMScrollScreenRight); X Widget widget; X X Scroll the screen one character cell in each direction X XXpwMScrollLines X XpwCallMethod(widget,XpwMScrollLines, row, rows, dist); X Widget widget; X int row, rows, dist; X X Scroll the text starting at row and extending to row+rows by distance dist. X Distance dist can be a positive or negative integer specifying the number X of character cells to move the text up/down. If rows is zero, the current X height of the window is used. X XXpwMScrollTail XXpwMScrollTails X XpwCallMethod(widget,XpwMScrollTail, col, row, dist); X XpwCallMethod(widget,XpwMScrollTails, col, row, rows, dist); X Widget widget; X int col, row, rows, dist; X X Scroll all of the text to the left of col, on row (extending row+rows) X left or right acording to distance dist. Dist is a positive or negative X integer specifying the number of character cells to move the text. X If rows is zero, the current height of the window is used. X XXpwMScrollTailLeft XXpwMScrollTailRight X XpwCallMethod(widget,XpwMScrollTailLeft, col, row); X XpwCallMethod(widget,XpwMScrollTailRight, col, row); X Widget widget; X int col, row; X X Insert or delete a character at col,row by scrolling the tail of the X line left or right by one character cell. X XXpwMInsertLineAtCursor X XpwCallMethod(widget,XpwMInsertLineAtCursor); X Widget widget; X X Insert a line at the current cursor position by scrolling the text on X that line, and lines below it, down. X XXpwMInsertCharAtCursor X XpwCallMethod(widget,XpwMInsertCharAtCursor); X Widget widget; X X Insert a blank space at the current cursor location by moving the X tail of the line right by one character cell. X XXpwMDeleteLineAtCursor X XpwCallMethod(widget,XpwMDeleteLineAtCursor); X Widget widget; X X Remove a line at the cursor position by scrolling the text below the X line up one character cell. X XXpwMDeleteCharAtCursor X XpwCallMethod(widget,XpwMDeleteCharAtCursor); X Widget widget; X X Delete the character under the cursor by scrolling the text on the X cursors line, after the cursors column, left one character cell. X X-- Clear Operations --------------------------------------------------- X XXpwMClear X XpwCallMethod(widget,XpwMClear, col, row, cols, rows); X Widget widget; X int col, row, cols, rows; X X Clear the region specified by (col, row, col+cols, row+rows). If cols or X rows are zero, the current length of the window are used. X XXpwMClearWindow X XpwCallMethod(widget,XpwMClearWindow); X Widget widget; X X Clear the whole window. X XXpwMClearLine X XpwCallMethod(widget,XpwMClearLine, row); X Widget widget; X int row; X X Clear the text on the specified row. X XXpwMClearLines X XpwCallMethod(widget,XpwMClearLines, row, rows); X Widget widget; X int row, rows; X X Clear the text on all lines starting at row, extending row+rows. If rows X is zero, the height of the window is used instead. X XXpwMClearTail X XpwCallMethod(widget,XpwMClearTail, col, row); X Widget widget; X int col, row; X X Clears text to the left of col, on row. X XXpwMClearTails X XpwCallMethod(widget,XpwMClearTails, col, row, rows); X Widget widget; X int col, row, rows; X X Same as ClearTail for multiple lines. If rows is zero, the height of the X window is used instead. X XXpwMClearChar X XpwCallMethod(widget,XpwMClearChar, col, row); X Widget widget; X int col,row; X X Clear the character cell (col, row). X X XXpwMClearLineAtCursor X XpwCallMethod(widget,XpwMClearLineAtCursor); X Widget widget; X X Clears the text on the current cursor row. X XXpwMClearTailAtCursor X XpwCallMethod(widget,XpwMClearTailAtCursor); X Widget widget; X X Clears the text to the left of the current cursor column, on the current X cursor row. X XXpwMClearCharAtCursor X XpwCallMethod(widget,XpwMClearCharAtCursor); X Widget widget; X X Clears the character under the cursor. X X-- Write Operations --------------------------------------------------- X XNOTE: For string operations, if a negative number is given as the length of Xthe string, the string is assumed to be a Poplog string, with its length Xstored two words before the start of the string pointer. X XXpwMWrite X XpwCallMethod(widget,XpwMWrite, col, row, index, lines, strs, off,len,clr); X Widget widget; X String strs[]; X Boolean clr; X int col, row, index, lines, off, len; X X Takes an array of strings, strs. Takes an index into the array, and the X number of lines from the array to draw. It starts at col, row on the X screen and draws len characters of the string strs[index+line] starting X at character off. If clr is true, the line is cleared first. This is X repeated for the next line, on the next row. If len is zero, the X string from character off onwards is drawn. X X XXpwMWriteLine X XpwCallMethod(widget,XpwMWriteLine, col, row, str, len, clr); X Widget widget; X String str; X Boolean clr; X int col, row, len; X X Writes len characters of the string str at col, row. If clr is true X the line is cleared first. If len is zero, the whole string is drawn. X XXpwMWriteLines X XpwCallMethod(widget,XpwMWriteLines, X col, row, index, lines, strs, len, clr); X Widget widget; X String strs[]; X Boolean clr; X int col, row, len, index, lines; X X Same as WriteLine, only it takes an array of strings strs and starts at X strs[index], continuing to strs[index+lines]. If len is zero, the X whole string is drawn X X XXpwMWriteSubstr X XpwCallMethod(widget,XpwMWriteSubstr, col, row, str, off, len, clr); X Widget widget; X String str; X Boolean clr; X int col, row, len, off; X X Writes len characters of the string str starting at character off, X at col, row of the window. If clr is true, the line is cleared first. If X len is zero, the string from character off onwards is drawn. X XXpwMWriteAtCursor X XpwCallMethod(widget,XpwMWriteAtCursor, str, len); X Widget widget; X String str; X int len; X X Writes the string str, of length len, at current cursors location. Moves X cursor to end of string. X XXpwMInsert X XpwCallMethod(widget,XpwMInsert, col, row, str, len); X Widget widget; X String str; X int col, row, len; X X Scrolls tail of text at col, row right by len characters, and then X draws the string. X XXpwMInsertAtCursor X XpwCallMethod(widget,XpwMInsertAtCursor, str, len); X Widget widget; X String str; X int len; X X Scrolls tail of text at the current cursor col and row right by len X characters, and then draws the string at the cursor row and column. X Moves the cursor to the end of the string. X X X-- Cursor and Misc Operations ------------------------------------------ X XXpwMCursorTo X XpwCallMethod(widget,XpwMCursorTo, col,row); X Widget widget; X int col, row; X X Move the text cursor to col,row. X XXpwMCursorUp XXpwMCursorDown XXpwMCursorLeft XXpwMCursorRight X XpwCallMethod(widget,XpwMCursorUp); X XpwCallMethod(widget,XpwMCursorDown); X XpwCallMethod(widget,XpwMCursorLeft); X XpwCallMethod(widget,XpwMCursorRight); X Widget widget; X X X Move the text cursor one character cell in each direction. X XXpwMBell X XpwCallMethod(widget,XpwMBell, volume); X Widget widget; X int volume; X X Calls XBell to make a beep of the specified volume (0-100). END_OF_FILE if test 19823 -ne `wc -c <'doc/ref/PopScrollText'`; then echo shar: \"'doc/ref/PopScrollText'\" unpacked with wrong size! fi # end of 'doc/ref/PopScrollText' fi if test -f 'doc/ref/PopText' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/PopText'\" else echo shar: Extracting \"'doc/ref/PopText'\" $4153 characters$ sed "s/^X//" >'doc/ref/PopText' <<'END_OF_FILE' XREF *PopText Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file descibes the PopText widget. For information on the Pop-11 interface Xto this widget, see HELP *PopText. For an overview of Poplog Widgets, see XHELP *PopWidgets. X X-- PopText Widget ----------------------------------------------------- X XSuperclass: (Athena) AsciiString Text X XThe PopText widget class is similar to PopCore and PopComposite in that Xit adds a callback action to an existing widget class (from the Athena XWidget Set). The callback is activated using an action in the Xtranslation table. The default translation table is show below. Users Xcan modify the translation table to trap specific events. X XThe PopText widget is useful in applications that want to use simple Xtext editors, and to be able to specify new methods for handling key and Xbutton events. X XThe PopText widget class variable is popTextWidgetClass. X XFor more information on the PopText widget, see the Athena Widget Set manual Xsection on the Text widget. X X X-- PopText Resources -------------------------------------------------- X XPopText inherits the resources from the AsciiText and Text Athena widget Xclasses. The following new resources are retrieved from the resource database Xor argument list at widget creation: X X========================================================================= XName Class RepType Default Description X========================================================================= XpopCallback Callback Pointer NULL Callback for Key/Btn events X XThe popCallback callback is used to notify applications of events. X X-- PopText Actions and Translations ----------------------------------- X XThe PopText widget class has one additional action to the text widget Xclass, called "notify-event". This action calls the 'popCallback' list, Xpassing the event to the callback list. The notify-event action can be Xspecified in the translations table to trap keys and buttons that the Xapplication specifies. The default translations are: X Xstatic char defaultTranslations[] = " XCtrl<Key>F: forward-word() \n\ XCtrl<Key>B: backward-word() \n\ XCtrl<Key>C: notify-event(CTR_C) \n\ XCtrl<Key>D: notify-event(CTR_D) \n\ XCtrl<Key>A: beginning-of-line() \n\ XCtrl<Key>E: kill-to-end-of-line() \n\ XCtrl<Key>H: delete-previous-character() \n\ XCtrl<Key>J: newline-and-indent() \n\ XCtrl<Key>K: backward-paragraph() \n\ XCtrl<Key>L: forward-paragraph() \n\ XCtrl<Key>M: newline() \n\ XCtrl<Key>P: delete-next-character() \n\ XCtrl<Key>V: next-line() \n\ XCtrl<Key>W: kill-selection() \n\ XCtrl<Key>Y: unkill() \n\ XCtrl<Key>Z: scroll-one-line-up() \n\ X<Key>Escape: notify-event(ESC) \n\ X<Key>Right: forward-character() \n\ X<Key>Left: backward-character() \n\ X<Key>Down: next-line() \n\ X<Key>Up: previous-line() \n\ X<Key>Delete: delete-previous-character() \n\ X<Key>BackSpace: delete-previous-character() \n\ X<Key>Linefeed: newline-and-indent() \n\ X<Key>Return: newline() \n\ X<Key>F1: select-start() \n\ X<Key>F2: select-end() \n\ X<Key>F3: backward-kill-word() \n\ X<Key>F4: beginning-of-line() kill-to-end-of-line() delete-previous-character()\n\ X<Key>F5: kill-to-end-of-line() \n\ X<Key>F6: backward-kill-word() \n\ X<Key>F7: kill-word() \n\ X<Key>F8: kill-selection() insert-selection()\n\ X<Key>F9: stuff() \n\ X<Key>R1: beginning-of-line() \n\ X<Key>R2: previous-page() \n\ X<Key>R3: end-of-line() \n\ X<Key>R4: beginning-of-line() \n\ X<Key>R5: next-page() \n\ X<Key>R6: end-of-line() \n\ X<Key>R7: backward-character() previous-line() \n\ X<Key>R9: forward-character() previous-line() \n\ X<Key>R13: backward-character() next-line() \n\ X<Key>R15: forward-character() next-line() \n\ X<Key>: insert-char() \n\ X<FocusIn>: focus-in() \n\ X<FocusOut>: focus-out() \n\ XCtrl<Btn1Down>: notify-event(BTN1) \n\ XCtrl<Btn2Down>: notify-event(BTN2) \n\ XCtrl<Btn3Down>: notify-event(BTN3) \n\ X<Btn1Down>: select-start() \n\ X<Btn1Motion>: extend-adjust() \n\ X<Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \n\ X<Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \n\ X<Btn3Down>: extend-start() \n\ X<Btn3Motion>: extend-adjust() \n\ X<Btn3Up>: extend-end(PRIMARY, CUT_BUFFER0) " X X END_OF_FILE if test 4153 -ne `wc -c <'doc/ref/PopText'`; then echo shar: \"'doc/ref/PopText'\" unpacked with wrong size! fi # end of 'doc/ref/PopText' fi if test -f 'doc/ref/XpwCallMethod' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/XpwCallMethod'\" else echo shar: Extracting \"'doc/ref/XpwCallMethod'\" $1287 characters$ sed "s/^X//" >'doc/ref/XpwCallMethod' <<'END_OF_FILE' XHELP *XpwCallMethod Jonathan Meyer, Jan 1990 X X XPoplog Widget Set, revision 3. X XXpwCallMethod is a C procedure that takes a widget, a method ID, and Xa variable number of arguments according to the method. X XIf the widget is a subclass of the PopCore widget class, XpwCallMethod Xlooks for the specified method ID in a table held in the widgets class Xstructure, and in the class structure of its superclasses. X XIf the method ID is found in the table, the associated method procedure Xis extracted and called. X XFor more information on the methods available to Poplog Widgets, see XHELP *XpwMethods. For more information on the methods calling technique Xsee SYSDOC *PopWidgets.imp. HELP *PopWidgets gives an overview of the XPoplog Widget Set. X XThe XpwCallMethod procedure is externally loaded into Pop-11. Because it Xtakes a variable number of arguments, which can be of different types, XLIB *EXTERNAL is NOT used. This means that, to use XpwCallMethod, you Xmust specify two extra arguments, telling external_apply how many Xarguments you are passing to C and whether the method returns a value or not. XFor Example, the call: X X XpwCallMethod(w, XpwMDrawPoint, 10,10, 4, false) X XCalls the C XpwCallMethod procedure with 4 arguments, and does not return Xa value. END_OF_FILE if test 1287 -ne `wc -c <'doc/ref/XpwCallMethod'`; then echo shar: \"'doc/ref/XpwCallMethod'\" unpacked with wrong size! fi # end of 'doc/ref/XpwCallMethod' fi if test -f 'doc/ref/XpwMethods' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/XpwMethods'\" else echo shar: Extracting \"'doc/ref/XpwMethods'\" $3715 characters$ sed "s/^X//" >'doc/ref/XpwMethods' <<'END_OF_FILE' XREF *XpwMethods Jonathan Meyer, Jan 1990 X XPoplog Widget Set, revision 3. X XThis file describes the methods available to Poplog Widgets. Methods are Xlike procedures except that a specific widget class can have several Xprocedures that get called when one method is invoked (methods are Xsubclass-to-superclass chained, so each superclass of a widget can have Xan interpretation for a method). Methods are invoked using XpwCallMethod. XSee REF *XpwCallMethod for more information on calling methods, or XSYSDOC *PopWidgets.imp for information about how methods are implemented. X X XThe methods listed here are desribed in more detail in the relevant XREF file. X X XPopCore Methods (See REF *PopCore) X XMethod Name Arguments Notes X======================================================================== XXpwMSetColor string either name or #rgb format XXpwMFreeColor string XXpwMSetFont string XXpwMFreeFont string XXpwMSetCursor shape shape in cursorfont.h XXpwMFreeCursor shape eg. XC_crosshair X X XPopPixmap Methods (See REF *PopPixmap) X XMethod Name Arguments Notes X======================================================================== XXpwMDrawArc x,y,w,h,a1,a2 XXpwMDrawArcs arcs,narcs XXpwMDrawLine x,y,w,h XXpwMDrawPoint x,y XXpwMDrawPoints pts,npts XXpwMDrawRectangle x,y,w,h XXpwMDrawRectangles recs,nrecs XXpwMDrawSegments segs,nsegs XXpwMFillArc x,y,w,h,a1,a2 XXpwMFillArcs arcs,narcs XXpwMFillPolygon pts,npts,shape,mode XXpwMFillRectangle x,y,w,h XXpwMFillRectangles recs,nrecs XXpwMDrawString x,y,str,len XXpwMDrawImageString x,y,str,len XXpwMPutImage image,sx,sy,ex,ey,w,h XXpwMGetImage x,y,w,h,msk,format XXpwMClearArea x,y,w,h XXpwMClearWindow none XXpwMDrawImage x,y,w,h,data XXpwMCopyFrom src_widget,x,y,w,h,ex,ey XXpwMCopyTo dst_widget,x,y,w,h,ex,ey X X XPopGraphic Methods (See REF *PopGraphic) X XMethod Name Arguments Notes X======================================================================== XXpwMAllocColorRange num,r1,g1,b1,r2,g2,b2 XXpwMAllocStoreColor r,g,b XXpwMCreateColormap - XXpwMFreeColormap - X X XPopScrollText Methods (See REF *PopScrollText) X XMethod Name Arguments Notes X======================================================================== XXpwMScroll col,row,cols,rows,x_dist,y_dist XXpwMScrollScreenUp - XXpwMScrollScreenDown - XXpwMScrollScreenLeft - XXpwMScrollScreenRight - XXpwMScrollLines row, rows, dist XXpwMScrollTail col, row, dist XXpwMScrollTails col, row, rows, dist XXpwMScrollTailLeft col, row XXpwMScrollTailRight col, row XXpwMInsertLineAtCursor - XXpwMInsertCharAtCursor - XXpwMDeleteLineAtCursor - XXpwMDeleteCharAtCursor - XXpwMClear col, row, cols, rows XXpwMClearWindow - XXpwMClearLine row XXpwMClearLines row, rows XXpwMClearTail col, row XXpwMClearTails col, row, rows XXpwMClearChar col, row XXpwMClearLineAtCursor - XXpwMClearTailAtCursor - XXpwMClearCharAtCursor - XXpwMInsert col, row, str, len XXpwMInsertAtCursor str, len XXpwMWrite col, row, index, lines, strs, off,len,clr XXpwMWriteLine col, row, str, len, clr XXpwMWriteLines col, row, index, lines, strs, len, clr XXpwMWriteSubstr col, row, str, off, len, clr XXpwMWriteAtCursor str, len XXpwMCursorTo col,row XXpwMCursorUp - XXpwMCursorDown - XXpwMCursorLeft - XXpwMCursorRight - XXpwMBell volume END_OF_FILE if test 3715 -ne `wc -c <'doc/ref/XpwMethods'`; then echo shar: \"'doc/ref/XpwMethods'\" unpacked with wrong size! fi # end of 'doc/ref/XpwMethods' fi if test -f 'doc/ref/XpwResources' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/ref/XpwResources'\" else echo shar: Extracting \"'doc/ref/XpwResources'\" $5311 characters$ sed "s/^X//" >'doc/ref/XpwResources' <<'END_OF_FILE' XREF *XpwResources Jonathan Meyer, Mar 1990 X XPoplog Widget Set, revision 3. X XThis file provides an index to the resources used in the Poplog Widget Set. XFor information about the Poplog Widget Set, see HELP *PopWidgets. XResources can be set and examined using XtGetValues and XtSetValues, Xor using LIB *XT_VALUE. X XCore and PopCore Resources (See REF *PopCore) X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNwidth Width Dimension 200 Window width XXtNheight Height Dimension 100 Window height XXtNx X Position 0 X coordinate in pixels XXtNy Y Position 0 Y coordinate in pixels XXtNborderWidth BorderWidth Dimension 1 Border width in pixels XXtNborderPixmap BorderPixmap Pixmap None Window border pixmap XXtNborderColor BorderColor Pixel foreground Window border color XXtNbackground Background Pixel XtDefault Window background color XXtNforeground Foreground Pixel XtDefault Window foreground color XXtNfont Font FontStruct XtDefault Font for text operations XXtNpointerShape Cursor Cursor None mouse cursor(cursorfont) XXtNtranslations Translations String Event-to-action translations XXtNpopCallback Callback Pointer NULL Callbacks for events XXtNautoFlush Boolean Boolean TRUE XFlush after methods? XXtNusersGC GC Pointer NULL Graphics Context for ops XXtNmodifiers Parameter Int None event->state modifiers XXtNdestroyCallback Callback NULL XtDestroyWidget callback XXtNmappedWhenManaged Boolean TRUE automatic XtMapWidget X X XPopPixmap resources (See REF *PopPixmap) X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNfunction Function Int XtDefault GC drawing mode XXtNsubwindowMode SubWindowMode Int XtDefault GC subwindow mode XXtNlineWidth LineWidth Int XtDefault GC line width XXtNlineStyle LineStyle Int XtDefault GC line style XXtNcapStyle CapStyle Int XtDefault GC cap style XXtNjoinStyle JoinStyle Int XtDefault GC join style XXtNprivateGC GC Pointer None Pixmap Graphics Context XXtNpixmap Pixmap Pointer None Pixmap of Widget. XXtNpixmapStatus PixmapStatus Cardinal PixmapOn Is Pixmap active? X X XPopGraphic resources (See REF *PopGraphic) X X=============================================================================== XName Class RepType Default* Description X=============================================================================== XXtNusePrivateGC Boolean Boolean TRUE See below XXtNmyGC GC Pointer NULL GC for window refresh XXtNswitchCmaps Boolean Boolean FALSE Automatic cmap install XXtNmouseX MouseLocation Int None Mouse X location in pixels XXtNmouseY MouseLocation Int None Mouse Y location in pixels XXtNbuttonEvent Callback Pointer NULL Called on ButtonPress XXtNkeyboardEvent Callback Pointer NULL Called on KeyPress XXtNmouseEvent Callback Pointer NULL Called on Enter/Leave XXtNmotionEvent Callback Pointer NULL Called on mouse Motion XXrNresizeEvent Callback Pointer NULL Called on Resize Req X X XPopScrollText resources (See REF *PopScrollText) X X======================================================================== XName Class RepType Default* Description X======================================================================== XXtNtopMargin TopMargin Dimension 0 Distance to start of text XXtNleftMargin LeftMargin Dimension 2 Distance to start of text XXtNfontWidth Width Dimension None Width of current font XXtNfontHeight Height Dimension None Height of current font XXtNcursorRow Position Position 0 Cursors Y location XXtNcursorColumn Position Position 0 Cursors X location XXtNcursorStatus CursorStatus Boolean TRUE Cursor on/off XXtNmouseX MouseLocation Int None Mouse column XXtNmouseY MouseLocation Int None Mouse row XXtNnumRows Dimension Dimension 24 Text columns XXtNnumColumns Dimension Dimension 80 Text rows XXtNexposedLines Parameter (int *) NULL Lines that need redrawing XXtNkey Key String NULL Ascii string of KeyPress XXtNkeyboardEvent Callback Callback NULL keyboard inputs callback XXtNbuttonEvent Callback Callback NULL Mouse buttonpress events XXtNmotionEvent Callback Callback NULL Mouse motion events XXtNdestroyCallback Callback NULL XtDestroyWidget callback END_OF_FILE if test 5311 -ne `wc -c <'doc/ref/XpwResources'`; then echo shar: \"'doc/ref/XpwResources'\" unpacked with wrong size! fi # end of 'doc/ref/XpwResources' fi if test -f 'doc/man/poplog.man' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/man/poplog.man'\" else echo shar: Extracting \"'doc/man/poplog.man'\" $12604 characters$ sed "s/^X//" >'doc/man/poplog.man' <<'END_OF_FILE' X.TH POPLOG 1 "December 1989" "Poplog V13.66" X XPoplog \- a multi\-language interactive software development environment X X.SH SYNOPSIS X.B pop11 [ \fI\+saved-image\fP ... ] X[ \fI argument .\.\.\fP ] X[ \fI :command\fP ] X.LP X.B ved [ \fIfilename\fP ] X.LP X.B prolog [ \fI\-|\+saved-image\fP ] X.LP X.B clisp [ \fI\-|\+saved-image\fP ] X.LP X.B pml [ \fI\-|\+saved-image\fP ] X.LP X.SH DESCRIPTION X X\fIPoplog\fP is an integrated, interactive, multi-language software Xdevelopment environment. It provides incremental compilers for POP-11, XPROLOG, COMMON LISP and ML. Features include a powerful extensible Xmulti-window text editor (\fIVed\fP), over 1700 documentation files, the \fI XPoplog Window Manager\fP (\fIPwm\fP), many demonstration and utility Xlibraries including an object oriented extension to Pop-11 known as X\fIFlavours\fP, compiler-building tools, and mechanisms for dynamically linking XPASCAL, FORTRAN and C programs so that they can be called from \fIPoplog\fP. XIt includes the source code for a large number of library packages, which are Xusually \fIPop-11\fP programs that the user can read and modify. X.LP XAt the heart of \fIPoplog\fP is the \fIPoplog Virtual Machine\fP. The X\fIPoplog\fP compilers translate program text and into a sequence of \fIPoplog XVirtual Machine\fP (\fIVM\fP) instructions, that are in turn compiled into Xreal machine code instructions. This system provides the programmer with a Xsuitable environment for rapid-prototyping, whilst also ensuring efficient Xcode execution. The provision of the \fIPoplog Virtual Machine\fP as a target Xfor compilers simplifies porting of Poplog languages, and programs written Xusing them, to new machines. X XPrograms written using AlphaPop on a Macintosh will run on implementations Xof Poplog on XWorkstations running UNIX, and DEC VAX machines running VMS. A list of Xcurrently supported hardware bases is available (see below for address). X.LP XThe \fIPoplog Virtual Machine\fP provides support for a large variety of Xdatatypes, including linked lists, arrays, strings, integers and floating Xpoint numbers. Users can define new datatypes. \fIPoplog\fP variables and Xconstants can either be dynamically or lexically scoped, and are weakly typed. X\fIPoplog\fP provides a trace and debugging facilities. It also has a very Xefficient storage manager, using a mark-and-sweep copying garbage collector, Xwhich is automatically replaced by a non-copying algorithm when there is not Xenough space for copying. \fIPop-11\fP processes start from under a megabyte Xin size. Prolog, Lisp or ML require more, but all start in less than two Xmegabytes. Poplog processes can grow to whatever size the machine and the Xoperating system will allow. X.LP XThe core language of \fIPoplog\fP is \fIPop-11\fP. \fIPop-11\fP combines the Xfeatures found in other AI languages like Lisp with a syntax that is similar Xin form to Pascal or C. \fIPop-11\fP code is easy to read, and includes many Xcontrol structures. For example, the following \fIPop-11\fP code prints the Xword "hello" out five times: X.sp X.in +8 X.nf Xrepeat 5 times X "hello" => ;;; print hello out five times Xendrepeat; X.fi X.in -8 X.LP XBecause the syntax of \fIPop-11\fP is very readable, it is easy to learn, and Xhas been found to be very effective as a teaching tool. However, \fIPop-11\fP Xprogrammers can also make use of rich syntactic structures, and the large Xnumbers of utilities, to write very complex and diverse packages. Since the Xeditor, the compiler and the debugging tools are all part of the same Xenvironment, programmers are saved from the laborious task of switching Xbetween editors and compilers, waiting for error messages from the compilers, Xand switching back to the editor again. X.LP X\fIPoplog\fP is far too complex to describe fully in a manual page entry. This Xdocument serves only as a pointer to the large amount of on-line documentation Xthat is available within the \fIPoplog\fP environment. X.SH COMMANDS X.LP X.TP X.I pop11 XLoads the default \fIPoplog\fP system, with only the \fIPop-11\fP compiler. X.TP X.I ved XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler, Xand then loads the \fIPoplog\fP editor, \fIVed\fP. This command can take one Xargument (a filename) that is passed to \fIVed\fP as the name of the initial Xfile to edit. X.TP X.I prolog, pop11 +prolog XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler, Xand then starts the \fIProlog\fP compiler (provided as a saved image). X.TP X.I clisp, pop11 +lisp XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler, Xand then starts the \fICommon Lisp\fP compiler (provided as a saved image). X.TP X.I pml, pop11 +pml XFirst loads the default \fIPoplog\fP system, with the \fIPop-11\fP compiler, Xand then starts the \fIML\fP compiler. X.in -8 X.SH OPTIONS X.LP XFor more information on \fIPoplog\fP parameter passing, see the Poplog Xhelp file HELP\ PARAMETERS, or the more detailed specification in XREF \SYSTEM. X.TP X\fI+saved-image\fP ... XLoads the \fIPoplog\fP environment and then looks for the specified X\fIPoplog\fP saved image. \fIPoplog\fP will search the directories specified Xin \fI$popsavepath\fP, and in the current directory. The suffix .psv is added Xto the filename if no suffix is specified. Several incremental saved images Xcan be loaded using the "+saved-image" form. Additional arguments specified Xusing the "-" flag will be passed into the \fIPoplog\fP environment. By Xdefault, such arguments are ignored, although the programmer may wish to Xdefine interpretations for them. If this option is given the \fI:command\fP Xoption must be omitted. For more information about saved images, see REF\ XSYSTEM. X.TP X.I :command XLoads the \fIPoplog\fP environment, and then executes the \fIPop-11\fP Xinstruction \fIcommand\fP. X.TP Xved \fIfilename\fP XLoads the \fIPoplog\fP environment, sets up the editor (\fIVed\fP), and Xreads \fIfilename\fP into a ved buffer, ready for editing. X X.SH POPLOG INITIALIZATION X X\fIPoplog\fP uses environent variables to store information about the location Xof files, defaults and documentation. These variables are usually initialized Xusing a shell script. For details see your local system administrator or the X\fIPoplog Users' Guide\fP. The \fIGuide\fP also explains how to use Xinitialization files, such as init.p, vedinit.p, init.pl, init.lsp, and Xinit.ml. Default scripts reside in the pop/com directory of the \fIPoplog\fP Xtree. These scripts are usually executed as part of the users \fI.login\fP Xscript. A typical login script would contain the following: X.LP X.ti+8n X\fBsetenv usepop /usr/local/pop13.66 (or whatever)\fP X.ti+8n X\fBsource $usepop/pop/com/poplog\fP X.LP X X\fIPoplog\fP initialization often prints out a message giving the Poplog Xversion, and adds the \fIPoplog\fP executables to the users PATH. X.LP XFor more information, contact your system administrator, or see the User Guide, Xor the online information in POPLOG HELP\ INITIAL. X.LP X.SH ENVIRONMENT VARIABLES X.TP X.I $usepop XHolds the path to the root of the \fIPoplog\fP directory tree. X.TP X.I $poplocal XHolds the path to the root of the \fIPoplog\fP local tree. This is used to Xstore site-specific libraries and documentation. X.TP X.I $popcom XSet to \fI$usepop\fP/pop/com. This directory holds several csh(1) scripts for Xmaking default saved images, and setting up the poplog environment. X.TP X.I $popsrc XSet to \fI$usepop\fP/pop/src. This directory contains the sources for the X\fIPoplog\fP environment, if provided. The sources may be in object file form. X.TP X.I $popsys XSet to \fI$usepop\fP/pop/pop. Contains the \fIPoplog\fP executable commands, Xincluding \fIpop11\fP, \fIprolog\fP, \fIpml\fP, \fIclisp\fP. Other commands Xinclude: X.sp X.in +8 X.nf X.ig X\fIteach\fP evokes \fIVed\fP with the TEACH *TEACH file. X\fIhelp\fP evokes \fIVed\fP with the HELP *TEACH file. X.. X\fIpwmtool\fP runs the Suntools Poplog Window Manager. X.ig X\fIv55\fP loads \fIVed\fP with the Visual 55 terminal setup. X\fIeliza\fP loads and runs the demo program Eliza. X.. X.fi X.in -8 X.TP X.I $popautolib, $poplocalauto XSet to $usepop/pop/lib/auto and $poplocal/local/auto respectively. The Xcompiler searches these directories when it is trying to evaluate an undefined Xidentifier. If a file is found with the same name as the identifier, it is Xcompiled. This enables the Poplog environment to be invisibly extended, whilst Xconserving memory usage. X.TP X.I $poplocalbin XDirectory containing local saved images. X.TP X.I $popliblib, $popdatalib, $poppwmlib, $popsunlib, $popvedlib XSet to directories containing library packages for Pop-11, Pwm, Sun consoles Xand Ved. X.TP X.I $popsavelib XSet to $usepop/pop/psv. This directory contains some standard saved images, Xincluding the Prolog, Lisp and ML saved images. X.TP X.I $popsavepath XLists of directories containing Poplog saved images. Users may add paths to Xdirectories containing their own saved images. By default, this is set to X$poplib:$poplocalbin:$popsavelib. X.TP X.I $poplib XUser definable. Holds the path to the users library directory. \fIPoplog\fP Xwill look in this directory for saved images and initialization files (see Xbelow). X.TP X.I $pop_{name} XWhen \fIPoplog\fP is executed, it checks the name of the command that it was Xexecuted by (ie. argv[0]). If this command was not "pop11", \fIPoplog\fP looks Xfor an environment variable starting with "pop_" and ending with argv[0]. If Xsuch a variable exists, \fIPoplog\fP treats the contents of the variable as Xthe arguments to \fIPoplog\fP. This is a convenient way of making new Xcommands. To make a command myved, which loads pop11 with the saved image Xcalled myved.psv, make a symbolic link between $popsys/pop11 and myved, and Xset the environment variable pop_myved to "+myved": X.sp X.in +8 X.nf Xln -s $popsys/pop11 myved Xsetenv pop_myved +myved X.fi X.in -8 X.LP X.SH FILES X X.TP X.I $poplib/init.p XAfter \fIPoplog\fP is loaded, the \fIPop-11\fP code in this file is compiled. XUsers can use this file define useful procedures and variables to tailor the X\fIPoplog\fP environment to their own tastes. X.TP X.I $poplib/vedinit.p XThis \fIPop-11\fP file is compiled when the \fIVed\fP editor is evoked. Users Xcan write programs to tailor the operation of \fIVed\fP, so that for example Xit behaves sensibly when different terminals are being used. This file can Xalso be used to define extra VED <ENTER> commands, or to modify the default Xactions that \fIVed\fP takes when a new file is edited (see XHELP\ VEDFILETYPES, HELP\ VEDVEDDEFAULTS). X.TP X.I $poplib/init.pl XA file containing PROLOG code that is compiled when \fIPoplog\fP is loaded Xwith the PROLOG compiler. X.TP X.I $poplib/init.lsp XA file containing LISP code that is compiled when \fIPoplog\fP is loaded with Xthe LISP compiler. X.TP X.I $poplib/init.ml XA file containing ML code that is compiled when \fIPoplog\fP is loaded with Xthe ML compiler. X.LP XAll of the above files are optional. If \fIPoplog\fP does not find them in the X$poplib directory, it searches the current directory. X X.SH BUGS X.LP XThe \fIPoplog\fP help file HELP *NEWS provides the latest information on Xproblems and changes in Poplog. Academic sites can mail Sussex University X(address below) with their problems. Other sites should contact ISL. Some Xsites may also have a bugreport mechanism, which automatically posts E-mail Xproblems to Sussex University. See HELP *bugreport, or contact your System XAdministrator. X X.LP X.SH "SEE ALSO" X X X.IB Poplog\ HELP\ files: X.LP XHELP *INITIAL, REF *SYSPEC, HELP *POPLOG, TEACH *TEACH, REF *SYSTEM X.LP XB. R. Barret, A. Ramsey and A. Sloman, \fI POP-11, A practical Language for XArtificial Intelligence\fP, Ellis Horwood, 1986. X.LP X.SH FURTHER INFORMATION X.LP X\fIPoplog\fP is the property of the University of Sussex. For information Xabout academic sales, contact: X X.sp X.in +8 X.nf XMs Alison Mudd XSchool of Cognitive and Computing Sciences XUniversity of Sussex XBrighton XSussex XBN1 9QH XPhone: (0273) 606755 XE-mail to alim@cogs.sussex.uk.ac X.fi X.in -8 X.LP XFor Commercial and overseas sales information, contact: X.sp X.in +8 X.nf XIntegral Solutions Limited XUnit 3, Campbell Court XBramley XBasingstoke XHampshire, RG26 5EG XPhone: (0256) 88028 Fax: 0256-882182 XE-mail to isl@integ.uucp X.fi X.in -8 X.LP XFor information about AlphaPop - a Pop-11 environment for the Macintosh, Xcontact: X.sp X.in +8 X.nf XCognitive Applications Ltd X4 Sillwood Terrace XBrighton XBN1 2LR XPhone (0273) 821600 X X.fi X.in -8 X X.SH AUTHOR XCopyright University of Sussex 1989. All rights reserved. X.br X Jonathan Meyer, December 15 1989. X X.ig X--- C.unix/doc/man/poplog.1 -------------------------------------------- X--- Copyright University of Sussex 1987. All rights reserved. ---------- END_OF_FILE if test 12604 -ne `wc -c <'doc/man/poplog.man'`; then echo shar: \"'doc/man/poplog.man'\" unpacked with wrong size! fi # end of 'doc/man/poplog.man' fi if test -f 'doc/sysdoc/PopWidgets.imp' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/sysdoc/PopWidgets.imp'\" else echo shar: Extracting \"'doc/sysdoc/PopWidgets.imp'\" $14708 characters$ sed "s/^X//" >'doc/sysdoc/PopWidgets.imp' <<'END_OF_FILE' XPoplog Widget Set Revision 3 X X X Jonathan Meyer, 14 Jan 1990 X X X SYSDOC *POPWIDGETS.IMP Implementation Notes X X X 1. Introduction X X X This document describes some of the implementation details of the X Poplog Widget Set. Specifically, details regarding Poplog Methods and X Graphic Context Issues are discussed. For further details about Widg- X ets and the X Toolkit, refer to the X Toolkit Intrinsics. Details X about individual widgets in the Poplog Widget Set are found in HELP X *POPWIDGETS. X X X 2. Methods X X X The Poplog Widget Set implements a new calling technique for accessing X procedures (called methods) that apply to widgets. Methods are class X properties, and so different classes respond to different methods. X Furthermore, superclass chaining is used, so that each widget class X can respond to a specific method differently. X X For example, the PopGraphic widget class interperts the XpwMDrawLine X method by drawing a line on the window of the widget. The PopPixmap X widget class responds to the XpwMDrawLine method by drawing a line on X the widgets Pixmap. Because the PopGraphic widget class is a subclass X of PopPixmap, drawing a line on a Graphics widget also causes the line X to be drawn on the Pixmap of the widget. This pixmap is used for X refreshing the window of the Graphics widget. X X X 2.1 Calling Methods X X X Methods are accessed using the procedure XPwCallMethod, which takes X a variable number of arguments depending on which method is called. X The prototype for XpwMCallMethod is: X X XpwMethodRet XpwCallMethod(w, id, arg1, arg2, ... argn); X Widget w; X XpwMethodID id; X XpwMethodArg arg1, arg2, ... argn; X X w X Specifies the Poplog widget to apply the method to. X X id X Specifies the Poplog identification number of the method. X X arg1, arg2 ... argn X A list of the arguments to pass to the method. X X X For example, one of the methods understood by graphics widgets is X XpwMDrawLine, which takes four integer arguments and draws a line X between them. To draw a line on a graphics widget between (1,1) X and (100,100), use: X X (void) XpwMCallMethod(w, XpwMDrawLine, 1, 1, 100, 100); X X X 2.1.2 Method Lookup X X X PopCore and its descendants have four additional fields in their class X structures: X X XpwMethodList methods; /* array of method structures */ X Cardinal num_methods; /* XtNumber(methods) */ X XpwApplyProc apply_proc; /* Procedure to apply a method */ X XpwAssocTable *methods_table; /* hashed table of methods X created at class initialize by the X PopCore class_part initialize. */ X X Method ID's are in fact integer numbers. They are defined in the X header file <XpwMethod.h>. They are used to look up XpwMethod X structures in the hash table methods_table. The hashing technique used X is similar to XAssocTables. X X The hashing table methods_table is constructed from the methods list X using XpwCreateAssoc, XpwCopyAssoc and XpwMakeAssoc at class X initialize, by the PopCore class_part initialize procedure. Methods X are found in the hash table using XpwLookupAssoc procedure. The X Create, Make and Lookup functions are identical to their XCreateAssoc, X XMakeAssoc and XLookUpAssoc equivelants, except they use XtMalloc, and X work with XpwMethodID's (not XID's), and so they do not have to worry X about different displays with the same XID's. The XpwCopyAssoc X function copies all of the entries of one association table into X another, using XpwMakeAssoc for each entry of the source table to X add it to the destination table. X X In most cases the class_initialize create more than one bucket per X method, so the XpwLookupAssoc procedure is likely to find the method X after one or two checks. This makes method lookup very rapid (much X more so than actions or callbacks). X X X 2.1.3 Method Interpretation X X X XpwCallMethod works by looking first at the widgets class for a X method with the right id. If the method is found, and there is an X apply_proc for that class, the apply_proc is called with the method, X the widget, and a pointer to arguments passed to XpwCallMethod. This X process is then repeated for the superclasses of the widget class. The X return value of the first apply_proc is returned as the result of the X XpwCallMethod, since C can only have one return value. X X XpwCallMethod will have no effect when called with widgets which are X not descendants of the PopCore widget, or widgets that do not have a X methods table, an apply proc, or a method with the corresponding X method ID. X X If a method has a special Cut flag set in its flags field, then the X superclass chaining is stopped at that method. X X 2.1.4 Apply Procs X X X Each XpwMethod structure currently contains: X X XpwMethodID id; /* ID of method (integer) */ X XpwMethodProc *proc; /* pointer to procedure of method */ X ShortCard num_args; /* number of parameters for proc */ X Cardinal flags; /* additional method info */ X caddr_t extenstion; /* for future use */ X X Apply procs are of the form: X X XpwMethodRet ApplyProc(w, method, args) X Widget w; X XtPopMethod method; X va_alist args; X X w X Specifies the Poplog widget to apply the method to. X X method X Pointer to the structure for the method being applied. X X args X An argument list in the format described by varargs(3). X X The apply procedure extracts the arguments from args, examines the X methods flags, adds any of its own arguments, and finally calls the X method (usually using the convenience routine XpwMakeCall). The X value returned by the method is passed back to the caller. Flags are X used to determine any additional arguments are be needed to apply the X method. X X For example,the XpwMDrawLine method requires a drawable and a graphics X context and takes four arguments. The Method Proc for XpwMDrawLine is X the Xlib line drawing function, XDrawLine. The Method structure for X the XpwMDrawLine method is therefore: X X { XpwMDrawLine, XDrawLine, 4, RequiresDrawable | RequiresGC } X X 2.2 Inheritance X X Currently, two of the additional fields of the class structure for X PopCore widgets can be inherited from the superclass. They are the X apply_proc field, and the methods_table field. To inherit a X superclass's methods, use the entry XtInheritMethods in the X methods_table field. To inherit the superclass's apply procedure, use X the entry XtInheritApplyProc in the apply_proc field. Additional X methods to those of the superclass can be specified in the methods X field. At class initialize, the methods from the superclass are first X added to the hash table for the class, and then those of the class are X added. Finally, the hash table is stored in the methods_table field. X This allows a class to inherit most of the methods of the superclass, X but override superclass methods or add its own methods as well. For X example, the PopGraphic class inherits all of the PopPixmap methods, X but adds a few of its own. Thus the class_part entry for the X PopGraphic widget is as follows: X X {/* popcore_part */ X /* methods */ popGraphicMethods, X /* num_methods */ XtNumber(popGraphicMethods), X /* apply_proc */ GraphicApplyProc, X /* methods_table */ XtInheritMethods, X } X X The class part definition, in PopCoreP.h, defines the new class fields X as: X XpwMethodList methods; /* array of method structures */ X Cardinal num_methods; /* XtNumber(methods) */ X XpwApplyProc apply_proc; /* Procedure to apply a method */ X XpwAssocTable *methods_table; /* hashed table of methods X X X 2.3 Notes X X Methods are useful for several reasons: X X o Interpretation of each method is left to the class. X X o Superclass chaining means that each superclass of a widget X can act on a method. X X o Methods can easily be constructed from standard functions, X making it very easy to add methods to widgets. X X This final reason was the main one for implementing methods: Rewriting X every Xlib drawing and text function for the graphics widget so that X the function would draw on both a pixmap and the window would have X been tiresome and expensive. Additionally, it would have involved a X large number of procedures, and hence larger object code size. X X The XtAssoc procedures are similarly useful. The X Toolkit has XtMal- X loc and XtFree procedures like Xmalloc and Xfree. Why it doesn't have X XtAssoc I don't know. X X 2.2.1 Naming conventions, and other issues. X X The Implementation of methods may change - it was designed in a hurry, X and could probably be fine tuned. However, the method calling tech- X nique is independant of the implementation, so this should not affect X application programers. X X There is a naming problem regarding methods - each different method X should be given a different number, and flags for the methods must X also be defined. This is currently done in one header file so that the X chances of overlap are reduced. Of course, it would not matter if two X different methods for different classes had the same ID, unless a X programmer went off and called a widget of one class with a method X from another. This would have upredictable and undesired affects. X Currently, method ID ranges have been assigned to different widgets X (this could be applied on a larger scale, so whole trees get a number X range to use, like network addressing): X X PopCore - 0-200 X PopPixmap - 200-400 X PopGraphic - 400-600 X PopScrollText - 600-800 X X X Similarly, flags that are used are defined in one file, so that dif- X ferent widgets don't use the same bit to represent different flags. X Some global flags should be defined: X X InheritApplyProc X Use the apply proc for the superclass to apply the method. X X ForceReturnVal X Make return value for this application of the method the X return value of the method call. X X MethodError X Call XtError to report an error message. The proc field X could be used to point to a string to use in the error X message. Or there could be a lookup table of method names to X id's, or the name could be stored in the method record. X X Others? X X Other possible improvements include: X X o Full argument specification, so that parameters other than X integers can be specified and returned. X X o More complex inheritance of methods. Ability to override or X augment superclasses methods. X X 3. Graphics Contexts X X The PopPixmap widget uses the initialize_hook, get_values_hook and the X set_values_hook entries of the class structure to initialize, get and X set fields of the graphics context from resource entries and argument X lists. These fields are called subparts, since they are not directly X part of the widget structure, but are pointed to by one of the fields X in the widget. X X The GC subpart of the widget is in fact the XGCValues entry of the X usersGC field of the widget. Since widgets can share Graphics contex- X ts, they can also share GCsubparts. Because of this, the hooks to X initialize and set subpart values must write changes to a different X XGCValues structure, and then compare this structure to the original. X If there are changes, then UpdateGC is called. In more detail, the X procedure works as follows: X X X 3.1 InitSubpartValues, GetSubpartValues, SetSubpartValues X X X The InitSubpartValues procedure uses a global XGCValues structure and X valuemask. First it copies the values from the current GC of the X widget into the global XGCValues structure (using GCsubpartCopy). Then X It calles XtGetSubresources to fill in the slots of the XGCValues X structure from the resource database. Finally, it examines the fields X of the structure that are resources, compares them to the original X XGValues for the widget, and sets the relevant fields of a valuemask X (using GCsubpartMask) so that a subsequent call to UpdateGC will X affect the slots that are specified in the resource database. X X SetSubpartValues works in a similar fashion, except that it calls X XtSetSubvalues to set the slots in the global XGCValues structure. X Then it calls UpdateGC with the correct valuemask (determined using X GCsubpartMask). X X GetSubpartValues simply calls XtGetSubvalues with the GCsubpart of the X widget. X X The SetValues procedures also use this Global XGCValues structure and X valuemask. Because of this, changes to the users graphics context X which involve parts of the widget structure (such as foreground co- X lour) and parts of the subpart structure (such as GC function) only X involve one UpdateGC call. X X X 3.2 Updating Graphics Contexts X X X UpdateGC(w, valuemask, values) X Widget w; X XtGCMask valuemask; X XtGCValues *values; X X w X Widget to modify X X valuemask, values X As for XChangeGC or XCreateGC X X UpdateGC first looks to see if the Graphics Context of the widget is X shared. Shared Graphics Contexts are read-only, and so should not be X modified. If the widget is sharing a graphics context, then a new X graphics context is created, with the current graphics contexts set- X tings. Finally XChangeGC is called to modify the graphics context. X X X 3.3 Notes X X X The subpart setting system works well, but it would be useful to be X able to use the same scheme to set and modify more than one graphics X context (determined by class?). Additionally, different subclasses of X the PopPixmap widget require different subparts of the graphics context X (the PopScrollText widget doesn't need the GCLineWidth resource!). X END_OF_FILE if test 14708 -ne `wc -c <'doc/sysdoc/PopWidgets.imp'`; then echo shar: \"'doc/sysdoc/PopWidgets.imp'\" unpacked with wrong size! fi # end of 'doc/sysdoc/PopWidgets.imp' fi echo shar: End of archive 2 $of 2$. cp /dev/null ark2isdone MISSING="" for I in 1 2 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked both archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 dan ----------------------------------------------------------- O'Reilly && Associates argv@sun.com / argv@ora.com 632 Petaluma Ave, Sebastopol, CA 95472 800-338-NUTS, in CA: 800-533-NUTS, FAX 707-829-0104 Opinions expressed reflect those of the author only.